That Was The WeekAnother fairly quiet wiki week as I've been doing on a lot of writing for the latest release, as well as preparing for the next using the info coming from the Agile meetings.
We're still inching towards 4.2: I think that should be with us this coming week. To that end I've been studying all the changes Atlassian have made and have set up a page listing the updates and who should be interested in what changes. I'm not trying to dictate to our users who can use what - in fact everyone can see the full list, so can look at what they want. What I've done is to suggest which departments the changes affect the most, and the updates that will be of most interest too them. In other words, to supply a level of focus so that people can see what's most important to them, rather than wading through a list playing spot-the-benefit. I find that making a person's ability to use Confluence easier is the best way to get them to become more active within the wiki.While I was looking through the updates, I came across an enormous list of functions that are either already available in the current version, or will be with 4.2. Although I like to think of myself as a fairly experienced user, there's clearly a lot that I wasn't aware of. Which is great: now there's even more to play with. BTW, if you're reading this and you're my boss, I mean 'there's even more functionality that will help make me even more productive.'
This list is called the 'Full Features List 180 features.' And comes with this helpful advice: Get comfortable.Tip of the WeekA brief look at one of Confluence's many functions.
Name: Status Macro
Available from: Insert/Other Macros
Have you seen the coloured Status macro that you can use to label a page's content? They come in four colours (grey, red, yellow and green) so you can use them to show an easy-to-see view of, for example, a task's status. You can add your own custom caption too. So you could use red to mean 'on hold', yellow for 'on going' and green to mean 'finished'.You can also use them to help organise your tasks in your own way. For example, I might have finished a piece of writing that's been sent for review. To save me having to trawl all the words on a page looking for its current status, I could add a yellow label at the top of the page saying 'Sent for review'. Which means I'll be able to see the page's status almost as quickly as it can load.
I'm not sure if there's maximum number of characters you can use as I gave up counting at 100. That's not very practical as you can't use line breaks, which means it extends across the page without breaking.Which isn't very handy, but I suspect that Atlassian didn't design it with that in mind.
Cheers
That Was The WeekAt the moment I'm involved in a lot of writing, both for our new release, which is for clients, and the Sprint releases, which are still internal. So I'm doing a lot less wiki work (boo hoo). Or am I?
Well yes, there are (still) only so many hours in the day, but there's still plenty to do on both sides of my job. For example, we're still integrating the existing systems and users from the companies we recently aquired - which means investigating how we'll import data from another wiki and integrate Sharepoint, and discussing how all this is going to be achieved. Fortunately Confluence and Sharepoint can do this, though it's too big a topic to discuss here (and I've never done it) but you can find out everything you need to know here.Living In Exciting TimesI've been having some great conversations with new colleagues about using the wiki to bring all our disperate documentation together, how to manage corporate standards, agreeing what these are, what kinds of docs are we creating, and who is producing the docs in the first place.
Although there's a mountain to climb on this front - and just identifying those who might be involved is a challenge - what I know is that there are more than a few people who see the value of using Confluence to share and collaborate. So I'm expecting to get much busier on the documentation management front over the coming months.
Not only will the effort needed go on the docs themselves, a lot of energy will be spent on encouraging people to us the wiki. I won't pretend that take up isn't on the slow side at times, but once people begin to use it, once they see the advantages and benefits for themselves, then you find they (very quietly) become fans.
To this end, I've set up a global docs space which all those involved in this area will use as the hub of all our activities and communications. The plan is to draw people in by getting them to use it without making a song and dance about it. Apart from using the wiki to keep all our thinking in one place, I'm also going to use it to eliminate using email by making sure we all use the Share and @mentions functionality. Just imagine: more results and less emails - bliss!
So watch this space - and feel free to offer advice!Feet Up On The Desk TimeMy copy of Sarah Maddox's book Confluence, Tech Comm and Chocolate, finally arrived yesterday. I've only glanced at it but it's stuffed with useful info. And given Sarah's experience as both a programmer and tech author, you can't go wrong buying this book if you're interested in using wikis and documentation. I'm just wondering about how much of my working day I can justify spending reading it.Upgrade 4.2 Is Go!Yes, we're just about to upgrade to 4.2 and I'm dead excited about that! It's full of great new features and improvements which are not only going to make my life as a tech writer easier, but also a lot more fun. I can't wait to get my hands on the new Editor and to see how the What's Popular voting buttons will enable us to improve our user content.
Another benefit of upgrading is, as mentioned in last week's blog, that we'll be able to link JIRA and Confluence. For me, this means better access to the info that I need for my documentation, but it will also benefit development and testing, because they'll have also have easier access to the same info. This means, for the first time, that we're all able to use the same info in one easy-to-find place.
And just to make that even easier (have to stop using that word...) we'll all be able to use single sign-ons to access both systems. An additional bonus is the fact that we will be able to share the plugins that both JIRA and Confluence use between each other. This means you only have to have the plugin installed in one to be able to use it in the other - how neat is that?
Atlassian have also been busy working on the new Atlassian Marketplace, which, if I understand it properly, is pretty much a one-stop shop for all plugins. It should ensure that not only are plugins easy to find, but they will also be compatible with the latest version of Confluence. This means that when you upgrade in the future, you won't have to wait for the plugins you use to be upgraded too. Which cuts out a lot of hassle or not being able to use a plugin until it has also been upgraded and is compatible. And how neat is that?
Cheers.
That Was The Week That WasEarlier this year my employer bought two companies who are also in the trading arena. One's based in Norway and Scotland, and the other's in Switzerland. This means we have even more wiki users to cater for and bring together. One of the problems any organisation faces when it's spread around the globe is creating unity. What can we do to bring people together so that we're connected?The answer is, of course, the wiki: home of sharing and collaboration. But you knew I'd say that. But it isn't so simple is it? Well, no. You have to get people involved and the only way to do that is to show how it benefits them. And how do you do that when there's 400 people working in offices as far apart as the USA, the UK and Singapore? Good question: it's not going to be easy, but I have a cunning plan.But First, This!When pages are edited one of the things that has to happen is that anyone who's interested in the page should be notified of the change. This is easy enough if they were the page's creator or if they're someone who's edited the page already - they get updated automatically. As does anyone who's been added to the page as a Watcher.But what about clients, how do they find out? Well it's very easy, all you have to do is add the Recently Updated macro to the home page of the space you want to take the data from, set up a couple of parameters - such as the way you want results displayed and the number of results shown, and press Save. Bingo! Finished.Every time the page is opened or refreshed the list updates automatically. By having this on our user information's home page, anyone who opens it can see not only the most recent updates, but who made them and when. These are all shown as links, and there's a link to the page itself so users can jump directly to it. Which is very handy if it's of particular interest to them. And it saves me bags of time too: in our previous wiki I had to add all this data manually, so I've saved myself as much as 30 mins or more per day just by using one simple macro that takes about two minutes to set up (and forget).Share and CollaborateWith something like eight different parts of the company producing a wide variety of documentation (everything from user info to sales and marketing) one of our challenges is making sure we're all using the corporate ID etc, but there's something else that's just as important: knowledge sharing.And knowledge can be anything from the sort of docs each office produces to the tools we use. So what can we do about sharing our knowledge, skills and experience? Where can we keep it and how to make sure everyone who's involved knows where they can find this info AND stay in the conversation loop?There's only one place of course: our very own wiki home; the Global Documentation space. At the moment this has very little info but it has it's own blog already (which is automatically included when you create a new space), plus a couple of other pages listing the team members and their details, including their areas of knowledge and skills.Over the next few days I intend to add some info about what our office produces and how, and once that's done I'll be adding all the documentalists as Watchers (Tools/Manage Watchers) so they'll all be updated when I publicise the space to them (by editing the home page, which will have a welcome message and explanation about what the space is for). Once that's done, we will run all our conversations through the wiki and not use email. That way everyone will be kept up to date with everything as it happens, and all the conversations, content updates and comments will be in one easy-to-search space, and nothing will be lost or duplicated.And once we've had that up and running for a couple of months, I intend to demo it to other departments and show them how, with very little effort, they can achieve the same thing and enjoy the benefits of sharing and collaborating.You can find out more about wiki collaboration by clicking here.
That Was The Week That WasIf you've been following my progress using the page includes macro you'll be delighted to know that this is now live to clients and working very well.
As usual some of my week was spent looking after other user's and helping them with their problems. Not that there are many: yes things do go wrong from time to time but I can't fault Atlassian's responses and help when problems arrise. Most of the issues I deal with are quite simply and easily resolved, for example:- people forgetting their log on details
- people wanting help with a task, for example, moving page.
- people finding something that needs fixing but they are unsure how go go about it.
Of course I have to police any content changes in the client areas, but given that I can review all changes from within the email notifications I recieve, this doesn't take very long. That said, the more content we have and the more people we have editing and contributing it, the more notifications I recieve. This is something you have to keep on the ball with, and I review every notification as it arrives. Time consuming? Yes. Pain in the backside? At times, sure, but if you don't do it you run the risk of something being published that you just might wish hadn't. So far, and because clients and colleagues are professionals, this hasn't been an issue.
Confluence for Technical DocumentationThis week also featured a very informative one hour webinar entitled Confluence as a Platform for Tech
Docs which was presented by, among others, Sarah Maddox, one of Atassian's technical writers and author of Confluence, Tech Comm, Chocolate. I was fortunate with the timing of this as it started at 1700 CEST, which meant the Australia participants were up well past their bedtimes and those in the USA had an early start.
Shortcuts - The FilmI recently described using shortcuts to speed up actions and production, but I think this could benefit from seeing this in action.
Now thanks to the power of Jing, you can do that very thing by clicking here.
Another working week has flown by and sadly it was a forum-free week: my time was devoted to more urgent tasks, such as writing a How-To guide on setting up and using blogs.Not that I mind giving people more info on how to make better use of Confluence, but sometimes when you really want to crack on with a project, it becomes a project that is destined to slip out your grasp. Ultimately that won't happen with the forum, because I'm determined not to let go of it until it's working and being used by clients.Shortcuts and MacrosOne of the jobs I've been doing as a background task for the last few weeks has been to convert the contents of a spreadsheet into a series of wiki pages.This equates to seven columns of data for each row, and several hundred rows, all of which have to be split into separate pages. Each page contains one or more table depending on the type of info. And while all of these are separate pages (99 in total), they all have to be grouped into one page so that they can be searched en-masse and printed as a PDF.The process for doing this is easier than you think, thanks to some helpful built-in functionality, aka, macros.Although adding all the data from the spreadsheet is laborious and time-consuming, once you've added them, the process of grouping them onto one page is very easy. All you have to do is insert a macro into the page you've created to group the content on, choose the page you want to include, then saving the macro and the page. The whole process takes about a minute normally.To do this you can use another one of Confluence's brilliant shortcuts. In this case the shortcut is the left facing curly bracket. Another example of a shortcut is pressing the 'E' key to open the current page in edit mode. Brilliant! It's this sort of thing turns Confluence into the Swiss Army Knife of technical documentation.When you're in Edit mode, enter a '{' and the Macro suggestions window opens, see Figure 1. Next press the Up arrow key to select the Open Macro Browser option, and press Return.Now start typing the letters 'I, N, C' (you can use lower case, these are capitalised for clarity) in the search box. Bear in mind that you don't even have to click in the search box as the cursor's already there (yep, even more labour saved). When you do this, the number of macros displayed is reduced to only those whose name contains the letters you enter.The next step is to select the appropriate macro and enter the only parameter it needs, the page's name. Figure 2 shows the Include Page macro, while Figure 3 shows the parameter I've entered in the Page to include field. All you have to do now is press Insert to close the macro window, and then save the page.When you do this, the macro automatically gets the content of the parameter page and displays it on the page you've just saved. To add all the other pages you need using a seperate Include Page macro for each one.The contents of the group page are automatically refreshed whenever you open it, so if the content of the parameter page is edited, it is the new content that is displayed.But wait, I hear you say, what if I want to include a page that is in another space, is that possible? Providing you have permission to view that page, then yes it is possible - and not only that, Confluence makes it easy for you to do so. Spaced InWhen you start typing in the Page to include field, after you've entered two or more letters a list appears based on those letters, see Figure 4.The list contains pages with that name from all the spaces you can see. If you run the mouse over the options, the name of the space appears, see Figure 5.All you have to do is select the appropriate option, press Insert and save the page. The parameter you select has both the space's key and the page's name, for example - spacekey:pagename.I'm not sure if there's a limit on the amount of Include Page macros you can use on one page, but I've used 67 so far one page and it still works exactly as expected. In most cases you won't need to use so many (and if you do stand by for some te-di-um) and the benefits are well worth the effort. For a start you'll have all the info in one place, which makes it very easy to create a PDF (in two clicks) with all the content from all the included pages. For searching, you'll have all individual pages which can all appear as separate results. And you'll have one page with all the appropriate info which you can search using your browser's built in functionality.Details and BenefitsWhat I like about the ease of use we get with the shortcuts and macros is the attention to detail they show. Both demonstrate how much thought Atlassian put into their products, thought that all Confluence users can benefit from.
As this is my first blog about using Atlassian's Confluence wiki as a technical author, I think a short explantion is required.I've been working as a technical author for about 15 years, mainly in software but I've also worked in other areas such as hardware and OM document sets. My current role is with a British software house working in trading and risk management.Three years ago we started using a wiki for all our client documentation as well as our intranet. Last year we acquired two other companies, both of whom used Confluence. After comparing the two systems we were using, we decided to use Confluence throughout the entire organisation. That done, we migrated our original wiki along with the two other Confluence instances into one brand new one. A great deal of thanks for the success of this project have to go to Clearvision, an Atlassian partner, who organised and oversaw the whole operation.I firmly believe that Confluence is the way forward for technical documentation, and, having used wiki technology for three years now, I believe I have the experience and knowledge to back this up. I intend to do this in the coming months as I describe and share my experiences and insights gained.But First, This!Last Monday, the 12th March, I attended Atlassian's Unite conference in London. This not only gave me first hand access to various Atlassians, including Mike Cannon-Brookes (co-founder and CEO) but also to a huge number of people who are connected to Atlassian. They are connected because they are users like me, or are Atlassian partners. For example, Clearvision and Adaptavist.The morning kicked off with a talk by Mike Cannon-Brookes that covered everything from it being Atlassian's 10th birthday (almost) to sending out their very first invoice, to where their tools are now and where they are heading. After that we got further insights from other Atlassians into Confluence and JIRA, which in my eyes are the core Atlassian products. What I really enjoyed about all this was the refreshingly straightforward way the company presents itself. It might be that they put their best face forward, but there is no BS here - something a lot of other businesses would do well to emulate.Lunch looked excellent but I forsook the very long queue for it for a small salad. On the upside I managed to get myself a place at Mike's table (Atlassian had several tables manned by staff who were there to spit out advice and information between mouthfulls of lunch). Our conversation ranged from the enormous size of Australia, to the un-helpfullness of the weather, to promoting the use of Atlassian products to colleagues and senior management. It was refreshing to hear a CEO straight-talking instead of spinning and weaving.The afternoon continued with a couple more talks about JIRA and building the Atlassian community in the UK, featured demos from a variety of clients that covered how they used Atlassian's products in their production systems, and gave insights into how they promoted the use of the technology to staff. This is something I'm keen to know more about as part of my role is to be the wiki evangelist, and although most people see the benefits as soon as they start using the software, there are a few you have to use velvet thumbscrews on.Also, you might expect these talks to be primarily from software and technology businesses, which is true, but in fact manufacturing industries also use Atlassian's products. For example, we were treated to a lively talk from the world's second largest pump manufacturer in the shape of Ole Kristensen, the lead consultant at Grundfos.The day ended with everyone hot-footing it to a nearby bar for refreshments and even more conversation, free food and business card collecting. Which demonstrates another thing Atlassian is very good at: community building - which is almost the primary function of all their products. Obviously, on such an occasion, you can't talk to everybody, but you can target a few people and build more personal relationships with them. For instance, I built on my existing relationship with Clearvision and various members of Atlassian's support teams, and launched a new one with Adaptavist. This resulted in getting some very heplful insights into using their Community Bubbles plugin, (which we're using to build our client forum) plus the promise of some free support when I start setting it up.All in all it was an excellent day and money well spent: I went home full of useful information, fired up with the knowledge I'd gained, and very pleased with the opportunities for various collaborations that had arrisen during the day and evening.Now all I have to do is write up my nine pages of notes for my management report, fill in my expenses claim, and get the forum set up and working: life as a technical author will never be dull again.And Now For Something Completely DifferentAs of next week, my blog will focus more on how I use Confluence for technical writing and related matters. This means promoting the wiki and its usage to colleagues, technological issues, developing the wiki (structurally and functionally) support issues etc etc. Please feel free to comment and share your thoughts and ideas.
|
RSS Feed
